Locust 簡介與安裝

Locust 是一款開源的負載測試工具，專為評估系統在高流量下的穩定性而設計。它採用 Python 編寫測試腳本，讓開發者能以程式化的方式精準模擬大量使用者與網站或應用程式的互動行為。

Locust 的核心優勢在於其靈活性與易用性。您可以透過簡潔的 Python 腳本定義使用者行為，例如登入、搜尋、提交表單等。測試過程中，Locust 會提供即時的效能報告，包含回應時間、請求成功率、每秒請求數 (RPS) 等關鍵指標，幫助您迅速定位系統瓶頸。

無論是測試 API、網站應用程式，或是 AI 模型等運算密集型服務，Locust 都能提供可靠且可擴展的解決方案，確保您的系統在高併發場景下依然穩定運行。

安裝 Locust 非常簡單，僅需執行以下指令：

pip install locust

使用 FastAPI 建立測試目標

在編寫第一個 Locust 腳本前，我們需要一個測試目標。直接對線上服務進行壓力測試可能引發預期外的問題，甚至法律風險。因此，除非您對目標系統有完全的控制權，否則強烈建議在本機建立一個簡單的 API 以供練習。

我們將使用 FastAPI 來快速搭建測試用的 API。FastAPI 是一個現代、高效能的 Python Web 框架，非常適合用於快速開發。

首先，安裝 FastAPI 與 ASGI 伺服器 Uvicorn：

pip install fastapi uvicorn

接著，在您的專案中建立 main.py 檔案，並貼上以下程式碼：

# main.py
from fastapi import FastAPI, Request

app = FastAPI(
    title="2025 鐵人賽 Demo API",
)

@app.get("/hello-world", summary="Returns a simple hello world message")
async def read_root(request: Request):
    return {"message": "Hello, World!"}

if __name__ == '__main__':
    import uvicorn
    uvicorn.run("main:app", host="0.0.0.0", port=8080, log_level="info", reload=True)

您的專案目錄結構應如下所示（不包含虛擬環境相關內容）：

LocustDemo
├── main.py     # FastAPI 應用程式
└── demo.py     # Locust 測試腳本

安置好檔案後，開啟終端機並執行 python main.py 來啟動 FastAPI 服務。成功啟動後，您會看到類似以下的輸出：

現在，您可以打開瀏覽器並訪問 http://localhost:8080/docs，應該能看到由 FastAPI 自動產生的 API 文件頁面。

Locust 快速入門

接下來，我們將編寫第一個 Locust 測試腳本。將以下程式碼複製到 demo.py 檔案中：

# demo.py
from locust import HttpUser, task, between

class QuickstartUser(HttpUser):
    # 模擬使用者在每次請求之間等待 5 到 9 秒
    wait_time = between(5, 9)
    # 設定測試目標主機
    host = "http://localhost:8080"

    @task # 定義一個使用者任務
    def hello_world_endpoint(self):
        """Sends a GET request to the /hello-world endpoint."""
        self.client.get("/hello-world")

接著，在終端機中執行 locust -f demo.py 來啟動 Locust：

看到以上訊息後，請訪問 http://localhost:8089 來開啟 Locust 的 Web UI。

直接點擊 "Start swarming" 按鈕，無需修改任何設定。頁面將跳轉到測試儀表板，並開始執行任務。

此時，觀察 FastAPI 服務的終端機，您會看到 /hello-world 端點正被持續呼叫，不過頻率不高，因為我們尚未進行詳細設定。

至此，您已完成 Locust 的快速入門。若要停止測試，請點擊 Web UI 右上角的 "STOP" 按鈕。否則，根據當前腳本，測試將會無限期地運行下去。

Statistics 頁面說明

啟動測試後，Locust Web UI 的 Statistics 頁籤會顯示詳細的請求統計數據。這些資料有助於評估 API 的效能表現與穩定性。以下是圖片中各欄位的詳細說明：

📊 表格欄位解釋

Aggregated

底部的 Aggregated 是綜合所有請求的總結資料（若您測試多個端點，這裡會統整所有結果）。

如何判讀結果？

• 若 # Fails 明顯偏高，建議檢查 API 是否有異常處理不完全或狀態碼回傳錯誤。
• 99%ile 數值特別重要，若與 Median 相差太大，可能代表偶發性延遲需進一步排查。
• Current RPS 過低通常表示測試設計過於保守，建議調整使用者數與等待時間（wait_time）參數以模擬更高流量。
• 若 Max 回應時間飆高，代表系統某些請求處理不穩，可能是記憶體抖動、GC、後端慢查詢等問題。

CHARTS 儀表板解讀

當您點擊 "Start swarming" 按鈕後，Locust 會即時生成如上圖所示的監控儀表板，協助使用者觀察系統在壓力測試下的表現。整體畫面分為三個主要區塊：

1. Total Requests per Second（每秒請求數）
   這個圖表以綠線表示每秒請求數（RPS, Requests Per Second），是衡量系統處理能力的關鍵指標。它代表在每一秒內，Locust 成功發出的 HTTP 請求數量。

   • RPS 越高，表示系統處理請求的速度越快。
   • 在測試過程中，若 RPS 保持穩定且錯誤率（Failures）為 0，代表系統在目前的使用者壓力下表現穩定。
   • 紅線則代表錯誤請求的數量，此圖中顯示為 0，說明目前沒有任何請求失敗的情況。

2. Response Times（回應時間）
   此圖表顯示兩個主要百分位數的回應時間：

   • 橘線為 50th percentile（中位數），表示一半的請求回應時間低於此值。
   • 紫線為 95th percentile，表示 95% 的請求回應時間低於此值。這可用來觀察是否有極端值拉高整體延遲。
     若圖中的回應時間曲線穩定、變化不劇烈，表示系統回應速度一致、可靠。

3. Number of Users（使用者數）
   最下方的藍線代表目前模擬的使用者數量。在這張圖中可以看到，Locust 漸進地增加了使用者數量，最後穩定在 3 位虛擬使用者。這種漸進式加載方式有助於觀察系統在不同壓力階段的表現。

附錄：什麼是 RPS？為什麼它很重要？

RPS（Requests Per Second，每秒請求數） 是性能測試中的核心指標之一，用來衡量系統在單位時間內能處理多少 HTTP 請求。簡單來說，它代表「系統吞吐量」的能力——系統能否在高併發下保持穩定、快速地處理大量請求。

📌 為什麼要關注 RPS？

在負載測試中，RPS 可直接反映出系統的承載極限。若 RPS 上升的同時，系統延遲（Response Time）保持穩定，代表系統具備良好的水平擴展性與資源調度能力。反之，當 RPS 到達某個峰值後系統開始出現延遲飆升或錯誤率增加，這就揭示了潛在的瓶頸。

實務標準：多少 RPS 才算好？

這取決於應用類型，無法一概而論，但以下是常見系統的參考基準：

RPS 是了解系統處理能力的重要指標，但應搭配延遲（Latency）、錯誤率（Error Rate）、資源使用率（CPU/記憶體）等資訊一併觀察，才能形成完整的效能輪廓。

🧪 RPS 不是越高越好，而是在可接受的延遲與錯誤率下，達到最大吞吐量才是最佳狀態。

明天，我們將深入介紹該如何建立測試用的使用者，並且針對這個使用者設定該執行的任務以及其他屬性。敬請期待！